Skip to main content
Feedback

Configuring API-level tracing

Updated 

API-level tracing controls give administrators fine-grained control over OpenTelemetry telemetry generation on deployed APIs. By selectively enabling tracing on mission-critical or troubleshooting-sensitive APIs and turning off tracing for high-volume or low-priority services, organizations can optimize observability backend costs while eliminating telemetry data noise.

Each API has a tracing mode: Basic, Intermediate, or Advanced. Intermediate is the default for every API. You can set an API's mode independently of the Gateway's global setting. For example, setting an API to Basic mode suppresses internal policy execution spans to save storage. Basic mode keeps root server and client spans, so distributed trace context headers (traceparent) continue propagating to downstream backends.

Platform privileges govern administrative capabilities. Users with edit access (API Management - APIs privilege) can modify tracing modes and parameters. Read-only privileges (API Management - Read APIs privilege) restrict users to viewing active configurations and monitoring live diagnostic sessions. Refer to API Management roles and privileges for which roles include each privilege.

Unlike global Gateway pipeline updates, per-API tracing changes take effect instantly without restarting the API Gateway. However, per-API controls remain subordinate to global Gateway settings. When global Gateway tracing is inactive, the Gateway locks and suppresses all API-level controls.

Prerequisites

  • Access to Boomi API Management with permissions to manage deployed APIs.
  • You must enable OpenTelemetry globally on the assigned API Gateway. If OpenTelemetry is disabled on the Gateway, the Gateway locks API-level tracing controls, and an informational banner instructs you to configure Gateway Settings first.

Configuration steps

To configure API-level tracing for a deployed API, perform the following steps:

  1. Log in to Boomi API Management.

  2. Navigate to Manage APIs > Deployed APIs.

  3. Select your deployed API and select Settings from the sub-menu.

  4. In the left navigation sidebar, select API Tracing.

  5. Verify your access level and Gateway status on the API Tracing screen:

    • Read-only access: If you hold the API Management - Read APIs privilege, a Read only badge appears next to the section header. See Role-based access control below.
    • Gateway disabled state: If global Gateway tracing is off, select the Gateway Settings button on the informational banner to enable OpenTelemetry globally first.

  6. Under Tracing Mode, select one of the three options based on your observability goals:

    • Basic: Select Basic to turn off internal policy spans for this specific API. This suppresses internal policy execution and content streaming spans while keeping root server and client spans and downstream trace context propagation (traceparent headers).
    • Intermediate (default): Every API starts on Intermediate unless you change it. It generates a single trace span per policy in execution sequence.
    • Advanced: Select Advanced to capture deep diagnostic metadata across policy boundaries for time-limited troubleshooting sessions.

  7. Select Save to apply your changes. The change takes effect immediately without restarting the Gateway.

What Basic mode suppresses

When an API is set to Basic mode, the Gateway suppresses unnecessary telemetry:

  • Internal policy spans suppressed: The Gateway suppresses all internal policy execution spans and policy content streaming spans. Always-streaming policies (such as Groovy scripts) and policies that apply to a specific scope (such as JSON Threat Protection or XML Threat Protection) do not emit internal spans.
  • Trace context propagation maintained: Basic mode controls what telemetry is recorded and does not break trace context propagation. The root Gateway server span (span.kind=server) and outbound Gateway client span (span.kind=client) remain active, so distributed trace headers (traceparent) pass intact to downstream integration runtimes and backend services.
  • Outbound policy calls: Outbound HTTP calls that policies make directly (such as HTTP Callouts or Traffic Shadowing) still generate HTTP client spans. The Gateway tracks these calls separately from internal policy spans.

Role-based access control (RBAC)

Editing API tracing settings requires edit access (API Management - APIs privilege):

  • Read-only privilege (API Management - Read APIs): When users have read-only access, a Read only badge appears next to the API Tracing section header. The interface disables all radio buttons, checkboxes, and time range fields, and hides the Save button. Read-only users can still view active Advanced session banners and live countdown timers.
On this Page